TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/(A)TA/(A)TAQ.ADF/Documentation/amigadex.doc

Text File | 1987-02-03 | 22KB | 462 lines

             Amigadex Version 1.0
        Copyright 1988 Mind's Eye SoftWyrks, Inc.
              P.O. Box 1253
          Westport, Massachusetts  02790
       Written by Ray Lambert  [tel. [phone]]


  Overview:  Amigadex is a disk-based 'address book.' It is
 intended to be used as a personal data base for the
names/addresses/phone numbers of all your friends and/or business
associates. The fields are pre-set for this purpose.  It may be
used to maintain a small mailing list, but it is not designed for
heavy 'industrial' usage; it may be found to be somewhat limited
for this sort of use.
 The data base is setup on the idea of 'cards.' Each entry into
the 'card file' has it's own separate card. Using Amigadex, you
can view and/or edit the cards that are in your card file. Also,
a flexible print utility is provided for labels, or if you just
want to make a print-out of certain entries in the data base.
 The print utility can also write cards to a text file,
permitting mail-merge type operations. The program is completely
mouse-driven.  Most of the gadgets that appear will be in the
shape of file cards, and will be referred to as 'card gadgets.'
 Most of the options available to you at any time will be
presented as card gadgets along the bottom of the Amigadex window
(which is also in the shape of a card :^) .


  Getting Started, The Card File: Since the job of Amigadex is
maintaining the card file, Amigadex will not execute if there is
none available. Therefore, you must supply the name of a card
file. If the file that you indicate doesn't exist, Amigadex will
create it for you, after verifying this action with you. There
are a number of ways to indicate a card file to use when invoking
the program.  The simplest method is to NOT indicate a card file.
 When this happens, Amigadex will display a requester asking you
to enter the name of the card file you wish to use. The default
card file name is 's:Amigadex.Cards', and this name will appear
in the requester for you to select or change. The remaining
methods are available either only from Workbench or only from the
CLI.


  Getting Started, Workbench:  From the Workbench you may put the
name of your card file in the 'Tool Types' field of the Amigadex
icon. You may do this by clicking once on the gadget, and then
selecting the 'Info' item from the 'Workbench' menu. The format
for the icon command is: 'CARDFILE=cardfilename' where
'cardfilename' is the name of your card file. As an example, the
default name would be entered into the icon as such:
'CARDFILE=s:Amigadex.Cards'. Note that it is desirable to use a
specific path to the card file because you never know what disk
directory your Amiga will be logged-into when you invoke
Amigadex.  Example: 'CARDFILE=Workbench/Amigadex/My.Cards'. Two
other parameters, 'SEARCHFLAGS=' and 'PRINTFLAGS=', can also be
defined as Tool Types. They will be discussed later.


  Getting Started, CLI: From the CLI you may pass the card file
name on the command line when invoking Amigadex. Example: 'RUN
AMIGADEX S:AMIGADEX.CARDS'. This will use the card file
'S:AMIGADEX.CARDS'. One additional option is to use a text editor
to create the Amigadex.Config file with the name of your card
file in it.


  Amigadex.Config file: To save you the trouble of going through
the steps just mentioned to start Amigadex (especially from the
CLI), one additional method of supplying Amigadex with the
information it needs is described here. If no card file is
specified on the command line (from the CLI) or if no card file
is specified in the icon (from Workbench) then Amigadex will
attempt to find a file called 'Amigadex.Config'. It will first
look in the currently logged directory for this file. If it
doesn't find it there it will look in your S: directory. (If it
still can't find the file it will resort to the requester
mentioned earlier). The config file contains the same information
as the icon. If you're using Workbench, the only benefit you gain
from using the config file is that you can directly modify it
from within Amigadex via the Config Window (see below). To modify
the icon, you must use Workbench's 'Info' menu option.
 The config file is just a text file with three lines in it. The
first line contains just the card file name, the second contains
the Search Flags (see below), and the third line contains the
Print Flags (also see below). This file can be edited using any
text editor that doesn't add any binary codes to the file.
 Amigadex will optionally create this file for you from
the Config window (see below). An example Amigadex.Config file
with all the default information in it is as follows:

S:Amigadex.Cards
YYYYYYY
YYYYYNN


  Search Flags: When browsing through your card file, Amigadex
will allow you to enter a Search String for selective viewing
and/or printing of entries in the file. Amigadex will search in
all the fields that are indicated by the Search Flags for the
Search String that you supply. First, a list of the available
fields..

 1. Name
 2. Address 1
 3. Address 2
 4. Address 3
 5. Address 4
 6. Phone #
 7. Comment

 From the Config window (see below) you may set/clear any of the
search flags. You may also set the initial flags either from the
Amigadex icon or in the Amigadex.Config file. If a flag is ON
then that will tell Amigadex to look in that field when
searching.


  Print Flags: The Print Flags are very much like the Search
Flags except in their usage by Amigadex. The Print Flags indicate
to Amigadex which fields should be printed in Print Mode (see
below). For example, if you are printing mailing labels, you most
likely would not want the Phone # field to be printed. You also
may not want the Comment field to be printed. Therefore, you
would clear the Print Flags for these two items, and they would
not be printed.


  Setting Flags: Search Flags may be defined in the Config Window
(see below) and Print Flags may be defined in the Print Set-up
Window, (also see below) once Amigadex is running. If you wish to
define them either within the icon or within the Amigadex.Config
file, you must understand how they are coded. A simple string of
seven 'Y' and/or 'N' characters are used to define the Flags in
the icon or in the config file. Each position in the string
corresponds to one field. Position #1 corresponds to field #1,
position #2 with field #2, etc. The default Search Flags are all
on, and therefore the string would look like this: 'YYYYYYY'
(without the quotes). The default Print Flags have all fields set
except #s 6 and 7. The resulting string would look like this:
'YYYYYNN'. Within the icon, these strings must be preceded by the
commands 'SEARCHFLAGS=' for the Search Flags, and 'PRINTFLAGS='
for the Print Flags. For example, the default Flags would be
defined as such:

 SEARCHFLAGS=YYYYYYY
 PRINTFLAGS=YYYYYNN


  The Card Window: When Amigadex executes it will display a
window which appears like a giant file card. This window is
affectionately referred to as the 'card window' throughout this
documentation. At the very top of the window is a blank area
which is used for quick messages. Below that area is the card
itself. Within the card are the field names and a line for each
field where information contained in that field will be displayed
and edited. Below the fields is an area which will be used to
display various card gadgets which give access to Amigadex's
various features. In between the message line and the top of the
main card, and to the left of the card's 'index tab', is found
two displays which will report the current card number and the
total amount of cards in the current card file at all times.


  Amigadex System Gadgets: Amigadex uses custom imagery for all
it's rendering in the card window, including the normal system
gadgets. The drag gadget is in the 'index tab' of the card window
and works exactly like a normal drag gadget. The depth gadgets
are located in the upper right corner of the window, as is normal
with other windows. They look similar to Intuition's depth
gadgets, except they contain little images of file cards. (What?
MORE cards???)  From the 'main menu' a Quit card gadget is
available in the lower right corner of the window which does the
job of a close gadget.
 One addition to the system gadgets is found just below the depth
gadgets in the upper right corner of the card window when the
Main Menu is active. This is an 'Iconify' gadget. It looks like a
file card with a fancy letter 'I' in it's center. When clicked,
it will remove the card window from the Workbench Screen and
replace it with a single tiny card which behaves similar to a
Workbench icon. It can be dragged around the Workbench screen,
and, when double-clicked, it will disappear and replace
Amigadex's card window on the Workbench Screen. 'Iconifying' puts
Amigadex 'to sleep' until you need it next. It will also free-up
about 16k of memory for system usage.


  The Main Menu: 'Menus' here refers to the lower area of the
card window where you will normally find up to five card gadgets
that allow you to do certain functions within Amigadex. The 'main
menu' is what you will first see once you've gotten into
Amigadex. The options available are:

 Add: Allows you to add a new card to the card file. Amigadex
will first search through the card file looking for deleted
cards.
  Pressing Esc during this searching process will abort it and
return  you to the main menu. If no deleted cards are found then
a new card is added to the file. Either way, you will be placed
into 'Edit Mode' (see below) to enter the information for the new
card.

 Browse: Allows you to look through and/or edit/delete cards in
the card file. This is referred to as 'Browse Mode' (see below).

 Print: Allows you to print the contents of cards. This is known
as   'Print Mode' (see below).

 Config: Allows you to define Search Flags, select a new card
file  and/or save a config file via the Config Window (see
below).

 Quit:  Quits Amigadex.


  Edit Mode: Edit mode allows you enter/edit information for any
card. If you are editing an existing card the information for
that card will be placed in the card window. A cursor will appear
on the first field and you may edit that information. Pressing
RETURN will move the cursor down to the next field. These are
standard Intuition string gadgets so you may also click anywhere
in any of the fields to move the cursor there to edit.
Right-Amiga-X will clear all the text on the line where the
cursor is. Right-Amiga-Q will replace the original contents of
the line as it was when the cursor first was placed on that line.
If the cursor should disappear, simply use your mouse to click on
one of the lines and the cursor will return. Two card gadgets
will be found on the card window at this point.

 File: Saves the card as it appears on the screen to the current
card file.

 Toss:  Aborts the edit process.  If changes have been made you
will be asked to verify this operation first.


  Browse Mode: Before entering Browse Mode you will be presented
with the 'Enter Browse Parameters' requester. Two string gadgets
and two card gadgets will be found in this requester. The string
gadgets allow you to enter the card number to begin searching at,
and a Search String for selective browsing. Leaving the 'Card
Number' gadget blank will assume that you wish to start at card
number one. Leaving the 'Search String' gadget blank will display
all cards in the file. Pressing RETURN when the cursor is in the
'Search String' gadget is the same as clicking on the 'Okay' card
gadget. Clicking on the 'Okay' card gadget instructs Amigadex to
continue and to use the information in the string gadgets to
browse with. Clicking on the 'Cancel' card gadget tells Amigadex
to forget what you just did and return you to where you last
where. If you haven't actually entered Browse Mode yet you will
be returned to the main menu. Once clicking on 'Okay' Amigadex
will search for the first card to display. If it cannot find a
card for whatever reason, a requester will appear informing you
that no cards where found and it will wait for you to click on an
'Okay' gadget. When a card is found you will then actually enter
Browse Mode. When in Browse Mode you will find five card gadgets
and two special 'Arrow gadgets'. The information for the current
card will be displayed in the card window. Amigadex allows you to
enter information for each field which may not completely fit in
the card window. The information will scroll left-right when you
type in Edit Mode. In Browse Mode however, if you wish to view a
piece of information which doesn't quite fit on a line, you will
need to use the Arrow Gadgets. These two gadgets are found on the
left border of the card window whenever you are in Browse Mode.
They will scroll the card information currently being displayed
left or right. The top gadget scrolls right, and the bottom
gadget scrolls left. The arrows found in the imagery will remind
you which is which. The five card gadgets are as follows:

 Next: Moves forward through the card file. The search
information  you specified is used to continue the search to show
you the next  card in the file. When the end of the card file is
reached Amigadex will re-position to the beginning of the card
file.

 Last: Moves backwards through the card file. The search
information you specified is used to continue the search to show
you the last or previous card in the file. When the beginning of
the file is reached Amigadex will re-position to the end of the
card file.

 Edit: Enters Edit Mode (see above) to allow you to edit the
current card.

 Delete: Used to delete the current card. You will always be
asked to verify your intentions.

 Done: Exits Browse Mode and returns to the main menu.

 One additional gadget is available in Browse Mode which is invisible.
This invisible gadget is located on the Card Number
which is displayed on the top of the card window (under the
message line). Clicking on the card number will bring-up the
'Enter Browse Parameters' requester to allow you to either jump
to another card in the file, change your Search String or both.


  Print Mode: Print Mode is where you will be allowed to print
the contents of cards in your card file. The 'Print Set-up
Window' allows you to enter all the information you will need to
configure the printing process, and you will always see the
set-up window when you click on the 'Print' card gadget from the
main menu. There are two modes of printing available, 'normal'
and 'continuous', which are explained below.


  Print Mode, The Print Set-up Window: This window is separate
from the card window, with normal system gadgets, etc. The
information is arranged in two columns within the window. On the
left is a series of toggle gadgets which allow you to set/clear
the Print Flags. These toggle gadgets appear as three-dimensional
cubes. When they are selected (turned on) a check-mark (which is
a close relative to the Amiga check-mark will appear inside the
cube. Alongside the toggle gadgets is text which identifies which
field each gadget represents. All fields which are selected here
(when the cube contains a check-mark) will be printed on your
labels, etc. The ones that are not checked, will not appear in
the printed output. The status of the Print Flags may be saved to
your 'Amigadex.Config' file from the Config Window (see below).
 The right column contains several string gadgets that allow you
to set search parameters, media size and output device. The
search parameters that you enter here work exactly like those set
in Browse Mode. The media size parameters are specified in
character positions. The 'Media Height' parameter is of most use
when printing labels as it allows Amigadex to calculate how many
lines to insert between labels in order to advance properly to
the next label. Your Media Height must be large enough to fit all
the fields that you select to print. The 'Media Width' parameter
is used to truncate any lines of text that are too long to fit on
the media. The default values for the Media size parameters are
suitable for standard size mailing labels.
 The 'Output Device' is where the printed output will be sent to.
This can be any valid AmigaDOS device. The default device is
PRT:, your Preferences printer. It could also be a file in case
you need to write the contents of some of your cards to a text
file to import the information into another program; a mail-merge
for instance. Below the 'Output Device' string gadget you will
find another toggle gadget with the words 'Continuous Mode'
beside it. When this item is checked, printing will take place in
'Continuous Mode' (see below), otherwise, printing will be done
in 'Normal Mode' (also see below).
 Finally, there are two card gadgets on the bottom of column two
of the set-up window. The 'Okay' card gadget will accept all the
input in the set-up window and begin the actual printing
activity. The 'Cancel' card gadget will exit the set-up window
and return you to the main menu, aborting the print operation.


  Print Mode, Normal Mode: The Normal Printing mode is very much
like the Browse Mode (described above). All the gadgets and
options that are available in Browse Mode are available in this
mode, with the exception of the 'Edit' and 'Delete' options, and
one additional card gadget for printing. The 'Print' card gadget
will send the currently displayed card to the Output Device that
you specified in the set-up window. This approach to printing
gives you full control over which cards get printed. You may
browse through your card file and print only the cards that you
wish. When you are done, click on the 'Done' gadget.


  Print Mode, Continuous Mode: Continuous Mode offers you a way
to quickly print a large batch of labels with as little
intervention from you as possible. All cards which are found to
match the Search String that you specify in the set-up window
will be sent to the Output Device. Note that the Search Flags
that you define in the Config Window (see below) or that you set
either in the Amigadex icon or in the Amigadex.Config file will
determine which fields are examined for the Search String; just
as in Browse Mode. While printing is taking place in this mode,
two card gadgets are available for you to click on:

 Pause: This will suspend the printing process until further
instructions are given by you via a 'pause requester', which will
appear after  clicking 'Pause'. The 'pause requester' will
contain two card gadgets to click on:

   Okay: Will resume the printing process exactly where it left
off.

   Cancel: Will abort the printing process and return you to the
main menu.

 Done: This will abort the printing process and return you to the
main menu.


  The Config Window: This window is a separate window like the
Print Set-up Window. It will allow you to set the Search Flags
and to change the card file that you are working with. It will
also allow you to save this information in an Amigadex.Config
file. Two columns of information will be presented to you. The
left column will appear almost exactly like the left column of
the Print Set-up Window (described above). A series of toggle
gadgets, each one representing a field, will be displayed with
the field name to the right of the toggle gadget. When the gadget
is toggled on, searching in that field is enabled.
 The right column contains a single string gadget and three card
gadgets.
The string gadget is used to enter the name of the card file that
you wish to work with. The name of the card file that you are
currently working with will be displayed by default. Below this
string gadget are the three card gadgets:

 Save: This option will attempt to create an Amigadex.Config
file. Saved within the Config file will be the name of the card
file which is displayed in the Card File string gadget, and the
current state of the Search Flags as well as the current state of
the Print Flags. This information will be used the next time you
start-up Amigadex, assuming that you save it properly. A simple
file requester will be displayed before Amigadex actually tries
to write the Config file out. This requester will allow you to
change the file name that Amigadex will use to save the file.
 Note however, as described above, when Amigadex runs it will
only look for a file called 'Amigadex.Config', first in the
current directory, and then in the S: directory if not found in
the current directory. After saving the Config file, the
information you defined in the Config Window will be used by
Amigadex to continue it's operation. It will try to access the
new card file that you enter (IF you enter a new card file of
course, and will prompt you to create the new card file if it
doesn't already exist.

 Use: This option will put the newly defined configuration
information into use without attempting to save it to a Config
file first.

 Cancel: This will cancel any changes you make to the
configuration information. If you actually have made changes you
will be asked to verify the operation.

 All three of the above options will close the Config Window and
return you to the main menu.


  Product Status:  Amigadex is ShareWare.  Anyone may distribute
it freely as long as all it's support files (including this .DOC
file) go along with it. It is illegal to collect any fee for
Amigadex, other than disk copying fees as normally charged by
user-groups. It is illegal to distribute Amigadex as part of any
commercial product without permission from Mind's Eye SoftWyrks,
Inc., or the author. If you find Amigadex to be a useful product,
you are asked to send a moderate fee to the address listed at the
top of this document to become a registered user. Checks should
be made payable to the author.
 The author and Mind's Eye SoftWyrks, Inc., assume no
responsibility for any damage or loss that may occur as a result
of using Amigadex.

 !PLEASE SUPPORT SHAREWARE!


Enjoy the program!

Ray




 Intuition, Workbench, CLI, Preferences, Amiga and AmigaDOS are
trademarks of Commodore-Amiga, Inc.